modules/ai-agents/examples/mcp-tools/processors/enrich_order.yaml-7-9 (1)

7-9: ⚠️ Potential issue | 🟠 Major

Static URL produces identical responses for every message — add Bloblang interpolation to identify the target record.

url: "https://api.example.com/lookup" carries no order or customer identifier, so every message through this processor will hit the same URL and receive the same generic response. The url field supports Bloblang interpolation using ${! ... } syntax, so the order or customer identifier present in the incoming message should be embedded in the URL (or passed as a query parameter). Without this, the processor cannot fulfill its stated purpose of enriching a specific order.

🐛 Proposed fix — inject the order identifier via Bloblang interpolation

-      url: "https://api.example.com/lookup"
+      url: "https://api.example.com/lookup?order_id=${! this.order_id }"

Adjust the field name (order_id) to match whatever identifier field is present in the incoming message payload.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/examples/mcp-tools/processors/enrich_order.yaml` around
lines 7 - 9, The http processor's static url field is causing identical
responses for every message; update the http -> url value to use Bloblang
interpolation (the ${! ... } syntax) to inject the order/customer identifier
from the incoming message (e.g., order_id or customer.id) into the path or as a
query parameter so each request targets the specific record; locate the http
processor's url entry in the enrich_order.yaml and replace the static string
with a Bloblang expression that references the correct identifier field used by
your pipeline.

modules/ai-agents/examples/mcp-tools/processors/openai_chat.yaml-15-15 (1)

15-15: ⚠️ Potential issue | 🟠 Major

Missing quotes in json() interpolation will cause a runtime failure.

In Redpanda Connect config string interpolation (${! ... }), the json() function requires a quoted string argument to reference a message field. json(feedback_text) passes an unquoted identifier, which cannot be resolved. The correct syntax is json("feedback_text"), as shown in the official documentation.

🐛 Proposed fix

-    Feedback: ${! json(feedback_text) }
+    Feedback: ${! json("feedback_text") }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/examples/mcp-tools/processors/openai_chat.yaml` at line 15,
The interpolation uses json(feedback_text) which is unquoted and will fail at
runtime; update the Redpanda Connect interpolation in openai_chat.yaml to call
json with a quoted field name (use json("feedback_text")) so the connector can
resolve the message field correctly and avoid the runtime error.

modules/ai-agents/examples/mcp-tools/inputs/event_driven_workflow.yaml-25-25 (1)

25-25: ⚠️ Potential issue | 🟠 Major

JSON injection risk: use Bloblang object construction instead of string interpolation for HTTP body.

${! this.order_id } is spliced directly into a JSON string literal. If order_id contains ", \, or , "injected": "value", the resulting body is either malformed JSON or an injection payload. json("items") has the same concern if items values contain special characters.

Use a mutation: processor to build the payload as a native Bloblang object and then serialize it, rather than constructing raw JSON via string interpolation.

🔧 Proposed fix — build body with a mutation processor

-        - check: this.event_type == "order_created"
-          processors:
-            - http:
-                url: "${secrets.INVENTORY_API}/reserve"
-                verb: POST
-                headers:
-                  Content-Type: application/json
-                body: '{"order_id": "${! this.order_id }", "items": ${! json("items") }}'
+        - check: this.event_type == "order_created"
+          processors:
+            - mutation: |
+                root = {
+                  "order_id": this.order_id,
+                  "items": this.items
+                }
+            - http:
+                url: "${secrets.INVENTORY_API}/reserve"
+                verb: POST
+                headers:
+                  Content-Type: application/json
+                body: '${! content() }'

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/examples/mcp-tools/inputs/event_driven_workflow.yaml` at
line 25, The HTTP request body currently uses string interpolation ("body:
'{\"order_id\": \"${! this.order_id }\", \"items\": ${! json(\"items\") }}'")
which allows JSON injection; replace this with a mutation processor that builds
a native Bloblang object (e.g., set root to {"order_id": this.order_id, "items":
this.items} via a mutation/bloblang mapping) and then serialize that object for
the HTTP body (use the serializer/json or a json() function) — locate the
existing "body: '...'" line and the HTTP request processor and replace the
interpolated string with the mutation-built object + JSON serialization.

modules/ai-agents/examples/mcp-tools/inputs/event_driven_workflow.yaml-16-34 (1)

16-34: ⚠️ Potential issue | 🟠 Major

processors is nested inside redpanda: — should be a sibling of it.

In Redpanda Connect, input-level processors are specified as a sibling of the input component key (e.g., redpanda:, kafka:), not as a child field of the plugin configuration. Here, processors: is indented at the same level as seed_brokers, topics, and tls, making it a field of the redpanda plugin config. Redpanda Connect does not recognize processors as a valid field for the redpanda input, so the switch routing logic will not execute.

🔧 Proposed fix — move `processors` to be a sibling of `redpanda:`

 label: order-workflow

 # tag::component[]
 redpanda:
   seed_brokers: [ "${REDPANDA_BROKERS}" ]
   topics: [ "order-events" ]
   consumer_group: "workflow-orchestrator"
   tls:
     enabled: true
   sasl:
     - mechanism: "${REDPANDA_SASL_MECHANISM}"
       username: "${REDPANDA_SASL_USERNAME}"
       password: "${REDPANDA_SASL_PASSWORD}"
-  processors:
+
+processors:
   - switch:
       - check: this.event_type == "order_created"
         processors:
           - http:
               url: "${secrets.INVENTORY_API}/reserve"
               verb: POST
               headers:
                 Content-Type: application/json
               body: '{"order_id": "${! this.order_id }", "items": ${! json("items") }}'
       - check: this.event_type == "payment_confirmed"
         processors:
           - http:
               url: "${secrets.FULFILLMENT_API}/ship"
               verb: POST
               headers:
                 Content-Type: application/json
               body: '{"order_id": "${! this.order_id }"}'
 # end::component[]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/examples/mcp-tools/inputs/event_driven_workflow.yaml`
around lines 16 - 34, The processors block is currently nested under the
redpanda input and therefore ignored; move the top-level processors: mapping so
it is a sibling of the redpanda: key (not indented under it). Specifically
relocate the entire processors: -> - switch: ... section out of the redpanda
plugin block so the switch processor (and its child http processors that call
the INVENTORY_API and FULFILLMENT_API with bodies referencing this.order_id and
json("items")) are at the same level as redpanda: in the YAML, ensuring Redpanda
Connect will recognize and execute the input-level processors.

modules/ai-agents/partials/integrations/continue-user.adoc-157-163 (1)

157-163: ⚠️ Potential issue | 🟠 Major

claude-haiku without a version number is not a valid model identifier.

The correct Anthropic API identifier for the Haiku model is claude-haiku-4-5. Using bare claude-haiku will fail when the request reaches the Anthropic API (or the gateway's model lookup). This unversioned identifier appears at lines 160, 278, 567, 667, and 750.

Additionally, the file uses dot notation for other Claude models (claude-sonnet-4.5, claude-opus-4.6) while Anthropic's official API identifiers use hyphen notation (claude-sonnet-4-5, claude-opus-4-6). If these are Redpanda AI Gateway–specific aliases, that should be made explicit in the documentation to prevent users from attempting to use the same model names outside the gateway and encountering errors.

✏️ Suggested fix

  "tabAutocompleteModel": {
    "title": "Gateway - Claude Haiku (autocomplete)",
    "provider": "anthropic",
-   "model": "claude-haiku",
+   "model": "claude-haiku-4-5",
    "apiKey": "YOUR_REDPANDA_API_KEY",
    "apiBase": "<your-gateway-endpoint>"
  }

Apply the same change to lines 278, 567, 667, and 750.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/partials/integrations/continue-user.adoc` around lines 157
- 163, Replace unversioned and dot-notated Anthropic model identifiers with
their official hyphenated, versioned names: change "claude-haiku" to
"claude-haiku-4-5", change "claude-sonnet-4.5" to "claude-sonnet-4-5", and
change "claude-opus-4.6" to "claude-opus-4-6" wherever these strings appear
(e.g., the "tabAutocompleteModel" block and the other model entries referenced
in the diff); if any of those shorter or dot-form names are Redpanda AI
Gateway-specific aliases, add a short note in the same doc block clarifying they
are gateway aliases and not valid for the official Anthropic API.

modules/ai-agents/pages/observability/ingest-custom-traces.adoc-88-91 (1)

88-91: ⚠️ Potential issue | 🟠 Major

Incorrect OTLP status code values — 0 is UNSET, not OK.

Lines 90 and 541 state 0 = OK / 0 for success, which contradicts the OTLP proto specification. The correct status code enum is: STATUS_CODE_UNSET = 0, STATUS_CODE_OK = 1, STATUS_CODE_ERROR = 2.

Users setting code = 0 expecting success will instead produce spans with UNSET status, which does not signal success—it means the instrumentation did not explicitly set a status.

Fix locations

Line 90:

-| Operation status with code (0 = OK, 2 = ERROR)
+| Operation status with code (0 = UNSET, 1 = OK, 2 = ERROR)

Line 541:

-* `status` with a `code` field (0 for success, 2 for error)
+* `status` with a `code` field (1 for success/OK, 2 for error; 0 means unset)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/pages/observability/ingest-custom-traces.adoc` around lines
88 - 91, Update the documentation for the `status` field to use the correct OTLP
enum mappings: change any instance that says "0 = OK" or "0 for success" to "0 =
STATUS_CODE_UNSET" and "1 = STATUS_CODE_OK", and ensure errors are shown as "2 =
STATUS_CODE_ERROR"; verify and update both occurrences referencing the `status`
field so the docs reflect that 1 is success (OK) and 0 means UNSET.

modules/ai-agents/partials/integrations/cline-user.adoc-313-319 (1)

313-319: ⚠️ Potential issue | 🟠 Major

CEL expression uses wrong request path — request.messages doesn't exist in the schema.

The CEL routing example uses request.messages[0].content, but the gateway's documented request object schema (defined in cel-routing-cookbook.adoc) exposes messages under request.body.messages. Using request.messages will cause a CEL evaluation error or silent mis-route when users apply this pattern.

🛠 Proposed fix

 // Route simple edits to cost-effective model
-request.messages[0].content.contains("fix typo") ||
-request.messages[0].content.contains("rename") ?
+request.body.messages.size() > 0 && (
+  request.body.messages[0].content.contains("fix typo") ||
+  request.body.messages[0].content.contains("rename")) ?
   "anthropic/claude-haiku" :
   "anthropic/claude-sonnet-4.5"

(The size() > 0 guard follows the safe-access pattern required for array fields, per cel-routing-cookbook.adoc.)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/partials/integrations/cline-user.adoc` around lines 313 -
319, The CEL example uses the wrong request path (request.messages) which
doesn't exist; update the expression to reference request.body.messages and add
a safe-access guard: replace occurrences of request.messages[0].content with
request.body.messages.size() > 0 &&
request.body.messages[0].content.contains(...) so the routing expression (used
where the ternary picks "anthropic/claude-haiku" vs
"anthropic/claude-sonnet-4.5") evaluates correctly without CEL errors.

modules/ai-agents/pages/mcp/remote/monitor-mcp-servers.adoc-71-96 (1)

71-96: ⚠️ Potential issue | 🟠 Major

Add --use-schema-registry=value flag to both rpk topic consume commands and fix inconsistent jq paths.

The redpanda.otel_traces topic uses Protobuf Schema Registry format, which requires explicit deserialization. Without the --use-schema-registry=value flag, rpk topic consume outputs raw Protobuf bytes, and piping to jq will fail.

Additionally, the two commands use inconsistent jq selectors:

• Line 74 correctly accesses the message via .value | select(...) (where .value is the rpk output wrapper)
• Line 95 incorrectly accesses select(.status.code == 2) at the top level

Both commands should use .value | select(...) to access fields within the deserialized message:

Corrected commands

[,bash]
----
rpk topic consume redpanda.otel_traces --use-schema-registry=value --offset start \
  | jq '.value | select(.instrumentationScope.name == "rpcn-mcp" and .name == "weather")'
----

...

[,bash]
----
rpk topic consume redpanda.otel_traces --use-schema-registry=value --offset start \
  | jq '.value | select(.status.code == 2)'
----

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/pages/mcp/remote/monitor-mcp-servers.adoc` around lines 71
- 96, Add the missing --use-schema-registry=value flag to both rpk topic consume
commands and normalize the jq selectors to read from the rpk output wrapper
(.value); specifically, update the first rpk invocation referenced by the
selector '.value | select(.instrumentationScope.name == "rpcn-mcp" and .name ==
"weather")' to include the flag, and update the error-filtering rpk invocation
to use '.value | select(.status.code == 2)' instead of selecting at the top
level so both commands correctly deserialize Protobuf via the schema registry
and access message fields consistently.

modules/ai-agents/pages/ai-gateway/builders/connect-your-agent.adoc-311-328 (1)

311-328: ⚠️ Potential issue | 🟠 Major

client is undefined in test_models() — broken example code

The test_models() function on Line 320 calls client.chat.completions.create(...) but client is never defined inside this function or at module level in this snippet. Users copying this example will receive a NameError: name 'client' is not defined at runtime.

🐛 Proposed fix

+import os
+from openai import OpenAI
+
+client = OpenAI(
+    base_url=os.getenv("REDPANDA_GATEWAY_URL"),
+    api_key=os.getenv("REDPANDA_API_KEY"),
+)
+
 def test_models():
     """Test multiple models through the gateway"""
     models = [

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/pages/ai-gateway/builders/connect-your-agent.adoc` around
lines 311 - 328, The test_models function calls client.chat.completions.create
but never defines client, causing a NameError; fix by either (A) changing
test_models to accept a client parameter (e.g., def test_models(client):) and
use that passed-in client for client.chat.completions.create, or (B) instantiate
the gateway client inside test_models before the loop (create the same client
object used elsewhere in examples) and then call client.chat.completions.create;
update any callers/examples accordingly so test_models has a valid client
instance.

.github/workflows/test-mcp-examples.yaml-53-62 (1)

53-62: ⚠️ Potential issue | 🟠 Major

Fix SC2144 and SC2211 shell script bugs in the cookbook test loop.

Two real actionlint/shellcheck errors that can cause tests to be silently skipped or misbehave:

1. SC2144 (line 56): -f doesn't work reliably with globs — the recommended fix is to use a for loop to expand the glob and test each result individually. When the glob expands to zero matches (no cookbook with test-*.sh), bash leaves the unexpanded literal as the argument; -f on that literal string returns false, silently skipping the directory.
2. SC2211 (line 59): ./test-*.sh is a glob used as a command name. If multiple scripts match, the first becomes the command and the rest become arguments, producing incorrect behaviour.
3. Bonus — bare cd without subshell: If cd fails mid-loop, subsequent iterations run in the wrong directory. A subshell eliminates the need for cd - entirely.

🐛 Proposed fix

-      - name: Run cookbook tests
-        run: |
-          for dir in modules/develop/examples/cookbooks/*/; do
-            if [[ -f "${dir}test-"*".sh" ]]; then
-              echo "Testing ${dir}..."
-              cd "${dir}"
-              ./test-*.sh
-              cd - > /dev/null
-            fi
-          done
+      - name: Run cookbook tests
+        run: |
+          for dir in modules/develop/examples/cookbooks/*/; do
+            for script in "${dir}"test-*.sh; do
+              if [[ -f "$script" ]]; then
+                echo "Testing ${dir}..."
+                (cd "${dir}" && ./"$(basename "$script")")
+              fi
+            done
+          done

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/test-mcp-examples.yaml around lines 53 - 62, The loop over
modules/develop/examples/cookbooks/*/ should be changed to explicitly expand
test-*.sh files rather than using -f on a glob and to execute each matching
script directly; replace the single if [[ -f "${dir}test-"*".sh" ]] and the
glob-as-command ./test-*.sh with a nested for that iterates over
"${dir}"test-*.sh, checks each file with a plain -f (or -x) test, and runs each
matched script as a single command, and run the per-directory execution inside a
subshell (e.g., (cd "$dir" && ./the-script)) so a failing cd cannot leak to
later iterations. This fixes SC2144 (don’t test unexpanded glob) and SC2211
(don’t use a glob as the command) while removing the need for cd -.

modules/ai-agents/partials/integrations/claude-code-user.adoc-152-167 (1)

152-167: ⚠️ Potential issue | 🟠 Major

Remove or clarify the claim about ${VAR} interpolation in ~/.claude.json's mcpServers section.

Official Anthropic documentation explicitly supports ${VAR} expansion only in .mcp.json files (project-scope), not in ~/.claude.json (local-scope). The note at line 167 claims this feature is available in both, which is inaccurate. To avoid silent configuration failures, either:

• Move the server configuration to a project-scope .mcp.json file where ${VAR} expansion is officially supported, or
• Remove the claim that ${VAR} interpolation works in ~/.claude.json and clarify the actual scope limitations.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/partials/integrations/claude-code-user.adoc` around lines
152 - 167, The note claiming `${VAR}` interpolation in the `mcpServers` section
of `~/.claude.json` is inaccurate; update the text around `mcpServers` to either
remove the assertion or explicitly state that `${VAR}` expansion is only
supported in project-scope `.mcp.json` files and not in `~/.claude.json`, and
show the actionable guidance to move the server config (e.g., entries using
`REDPANDA_GATEWAY_URL` and `REDPANDA_API_KEY`) into a `.mcp.json` if
environment-variable interpolation is required.

modules/ai-agents/partials/integrations/claude-code-user.adoc-72-83 (1)

72-83: ⚠️ Potential issue | 🟠 Major

--api-provider and --base-url are not valid claude config set flags — use environment variables instead.

The correct way to route Claude Code through a custom gateway is to set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN. These can be configured as shell environment variables or persisted in ~/.claude/settings.json:

🐛 Proposed fix

-To route Claude Code's LLM requests through the gateway instead of directly to Anthropic:
-
-[,bash]
-----
-claude config set \
-  --api-provider redpanda \
-  --base-url <your-gateway-endpoint>
------
-
-This routes all Claude model requests through your gateway, giving you centralized observability and policy enforcement.
+To route Claude Code's LLM requests through the gateway instead of directly to Anthropic:
+
+[,bash]
+-----
+export ANTHROPIC_BASE_URL="<your-gateway-endpoint>"
+export ANTHROPIC_AUTH_TOKEN="<your-api-key>"
+-----
+
+Alternatively, add these to `~/.claude/settings.json`:
+
+[,json]
+-----
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "<your-gateway-endpoint>",
+    "ANTHROPIC_AUTH_TOKEN": "<your-api-key>"
+  }
+}
+-----
+
+This routes all Claude model requests through your gateway, giving you centralized observability and policy enforcement.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/partials/integrations/claude-code-user.adoc` around lines
72 - 83, The docs incorrectly show using flags with the CLI command "claude
config set"; replace that guidance to instruct users to set the
ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN environment variables (or store them
in the Claude settings JSON) to route Claude Code through a custom gateway
rather than using the non-existent --api-provider and --base-url flags; update
the example block and surrounding text to reference ANTHROPIC_BASE_URL and
ANTHROPIC_AUTH_TOKEN and mention the alternative of persisting those values in
the Claude settings JSON.

modules/ai-agents/examples/pipelines/fraud-detection-routing.yaml-33-35 (1)

33-35: ⚠️ Potential issue | 🟠 Major

root = this in result_map likely overwrites original transaction fields; silent JSON-parse failure creates a false-negative path.

Two distinct issues here:

1. root = this clobbers the source message.
The branch processor maps the result "back into the source message" via result_map. The canonical pattern for adding a field from branch results is root.some_field = this, not root = this. Examples in the docs consistently use root.cardinality = this so that original message fields are preserved. With root = this, the original id, amount, merchant, and user_id fields are replaced by the LLM agent's response object before root.fraud_analysis is even set. Drop the root = this line:

🐛 Proposed fix

         result_map: |
-          root = this
           root.fraud_analysis = content().parse_json().catch({})

2. Silent false-negative when JSON parsing fails.
LLMs frequently wrap JSON in markdown fences (```json ... ```). When that happens, content().parse_json() throws, .catch({}) substitutes an empty object, this.fraud_analysis.fraud_score is null, and the switch cases both evaluate to false—routing every transaction to transactions-cleared. For a fraud detection pipeline this is a dangerous silent failure mode. Add explicit error handling:

🛡️ Suggested hardening

         result_map: |
           root.fraud_analysis = content().string().re_replace_all("```(?:json)?\\s*", "").parse_json().catch({})
+
+    - mapping: |
+        root = this
+        meta fraud_score = this.fraud_analysis.fraud_score.number().catch(-1)

Using -1 as the catch value means a parse failure will never silently clear a transaction — it routes to transactions-cleared only when the score genuinely indicates no fraud, rather than when the LLM response was unparseable.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/examples/pipelines/fraud-detection-routing.yaml` around
lines 33 - 35, The result_map currently uses "root = this" which overwrites the
original transaction fields; remove the "root = this" assignment and instead
only assign the branch output into a nested field (e.g., set root.fraud_analysis
= content().parse_json()...), and harden JSON parsing by stripping code fences
before parsing and ensure parse failures produce a sentinel value (e.g., set
root.fraud_analysis.fraud_score =
content().parse_json().catch({}).fraud_score.number().catch(-1) or equivalent)
so that parse errors yield -1 rather than silently treating the transaction as
cleared; update the mapping references (result_map, content().parse_json(),
root.fraud_analysis, fraud_score.number().catch(-1)) accordingly.

modules/ai-agents/examples/agents/compliance-agent-prompt.txt-68-68 (1)

68-68: ⚠️ Potential issue | 🟠 Major

Factual error: fraud dispute acknowledgment is 24 hours, not 24 days.

The "24-30 days" range reads as a day range. However, check_regulatory_requirements.yaml stores the fraud branch timeline as "acknowledge_dispute_hours": 24—a 24-hour deadline, not 24 days. The billing-error branch uses acknowledge_dispute_days: 30, which is where the "30" comes from. As written, an LLM following this prompt would tell users that fraud disputes can be acknowledged in up to 24-30 days, which contradicts both the tool data and Regulation E expectations.

✏️ Suggested fix

-  - Acknowledge dispute: 24-30 days (varies by type)
+  - Acknowledge dispute: 24 hours (fraud) or 30 days (billing error)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/examples/agents/compliance-agent-prompt.txt` at line 68,
The prompt line "Acknowledge dispute: 24-30 days (varies by type)" is factually
wrong for fraud disputes; update the prompt in compliance-agent-prompt.txt to
distinguish the two branches: state fraud disputes must be acknowledged within
24 hours and billing errors within 30 days, matching
check_regulatory_requirements.yaml's keys acknowledge_dispute_hours (24) and
acknowledge_dispute_days (30); ensure the wording explicitly references "fraud:
24 hours" and "billing errors: 30 days" so an LLM will not conflate the
timelines.

modules/ai-agents/pages/agents/tutorials/transaction-dispute-resolution.adoc-461-479 (1)

461-479: ⚠️ Potential issue | 🟠 Major

Tutorial grants overly broad cluster-level ACLs without a least-privilege caveat.

Line 463 instructs users to click the Clusters tab and select Allow all, and line 477 does the same for Consumer groups. For a tutorial the reader will likely follow literally, granting blanket cluster-level and consumer group-level permissions without noting this is for tutorial convenience (and should be scoped down in production) sets a poor security example.

Add a note clarifying that Allow all is used here for simplicity and that production deployments should scope ACLs to only the required operations.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/pages/agents/tutorials/transaction-dispute-resolution.adoc`
around lines 461 - 479, The tutorial currently instructs selecting "Allow all"
on the Clusters tab and Consumer groups tab, which is overly broad; update the
text around the "Clusters" and "Consumer groups" instructions (and the ACL
example for principal `dispute-pipeline-user`) to add a concise caution: state
that "Allow all" is used here for tutorial simplicity and must NOT be used in
production, and advise scoping ACLs to the minimal required hosts, resource
types/selectors (e.g., topic names starting with `bank.`) and operations for
production deployments or providing links to docs on least-privilege ACLs.

modules/ai-agents/partials/ai-hub/configure-ai-hub.adoc-11-12 (1)

11-12: ⚠️ Potential issue | 🟠 Major

Google Gemini is claimed as a supported provider but is entirely absent from the backend pools, routing rules, and credential management sections.

The introduction and learning objectives (lines 7, 11, 48) state "OpenAI, Anthropic, and Google Gemini" as supported providers, but:

• The 6 documented backend pools cover only OpenAI (2 pools) and Anthropic (4 pools) — no Gemini pool exists.
• The 17 routing rules section describes only openai/* and anthropic/* prefixes.
• There is no "Add Google Gemini credentials" section under Manage provider credentials.
• Cost tracking lists only OpenAI and Anthropic.

Either remove Google Gemini from the overview claims, or add the corresponding backend pool documentation, routing rules (for example, google/* prefix), and credential management steps.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/partials/ai-hub/configure-ai-hub.adoc` around lines 11 -
12, The doc claims "OpenAI, Anthropic, and Google Gemini" but Gemini is missing
from backend pools, routing rules, credential management, and cost tracking;
either remove Gemini from the overview or add corresponding documentation: add a
Gemini backend pool entry under "backend pools" (e.g., a named Gemini pool),
include routing rules that match the Gemini prefix (recommend using "google/*"
or "gemini/*" alongside existing `openai/*` and `anthropic/*` examples), add an
"Add Google Gemini credentials" subsection under "Manage provider credentials"
showing how to store provider keys, and update the Cost tracking section to
include Gemini; update mentions in the introduction and learning objectives to
match whichever option you choose so the three lists are consistent with the
rest of the doc.

modules/ai-agents/pages/ai-gateway/mcp-aggregation-guide.adoc-569-569 (1)

569-569: ⚠️ Potential issue | 🟠 Major

Multiple PLACEHOLDER comments in configuration examples.

Lines 569, 631, and 991 contain # PLACEHOLDER: ... comments inside code blocks that will be rendered to users. These should either be replaced with actual configuration formats or removed before publishing.

Also applies to: 631-631, 991-991

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/pages/ai-gateway/mcp-aggregation-guide.adoc` at line 569,
Replace or remove the inline placeholder comments that will render to users
(e.g. the strings "# PLACEHOLDER: Actual configuration format" and other "#
PLACEHOLDER: ..." occurrences) in the mcp-aggregation-guide.adoc code blocks;
either substitute each placeholder with the actual configuration snippet/example
expected in that block or delete the placeholder lines so no "# PLACEHOLDER"
text appears in the published code examples, and ensure the surrounding code
block remains syntactically valid for AsciiDoc rendering.

modules/ai-agents/pages/ai-gateway/mcp-aggregation-guide.adoc-438-438 (1)

438-438: ⚠️ Potential issue | 🟠 Major

Unresolved PLACEHOLDER comment will be visible to readers.

Line 438 contains // PLACEHOLDER: Confirm orchestrator API details which is rendered as an AsciiDoc comment and won't appear in HTML output, but it signals that the content below (tool name, input schema, security, limitations) is unconfirmed. If this information is speculative, it risks misleading users.

Would you like me to open an issue to track confirmation of the orchestrator API details before this page goes live?

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/pages/ai-gateway/mcp-aggregation-guide.adoc` at line 438,
Replace the unresolved "// PLACEHOLDER: Confirm orchestrator API details" marker
in mcp-aggregation-guide.adoc with either the confirmed orchestrator API details
(tool name, input schema, security, limitations) or a clear TODO that references
an issue number tracking the confirmation; update the section that follows the
placeholder to include the verified API fields under the appropriate headings
and, if you can't confirm now, create the issue and insert the issue link next
to the TODO so readers and reviewers know this is intentionally outstanding
rather than speculative.

modules/ai-agents/partials/ai-hub/gateway-modes.adoc-66-70 (1)

66-70: ⚠️ Potential issue | 🟠 Major

Contradictory information about Google Gemini support.

Lines 66 and 70 list Google Gemini as a supported provider in AI Hub mode, but the "Supported providers" section (lines 127–134) explicitly states only OpenAI and Anthropic are supported and that "Google AI…[is] not yet supported in AI Hub mode." One of these sections is incorrect and should be updated for consistency.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@modules/ai-agents/partials/ai-hub/gateway-modes.adoc` around lines 66 - 70,
The "AI Hub mode" description and the "Supported providers" section conflict
about Google Gemini support; update the content so both are consistent by either
removing Google Gemini from the introductory copy under the "What it is"
paragraph or by adding Google Gemini to the "Supported providers" list with
appropriate caveats; specifically edit the "AI Hub mode" description text that
currently names OpenAI, Anthropic, and Google Gemini and/or the "Supported
providers" section so both reference the same supported providers (OpenAI and
Anthropic) or include Google Gemini support details and status, ensuring the two
sections (the "What it is" paragraph and the "Supported providers" section)
match.